---
sidebar_label: Docker
sidebar_position: 2
description: Hasura with Docker for CockroachDB
keywords:
  - hasura
  - docs
  - databases
  - cockroachdb
  - docker
---

import Thumbnail from '@site/src/components/Thumbnail';

# Get Started with Hasura (Docker) & CockroachDB

## Introduction

### Pre-requisites

- [Docker](https://docs.docker.com/install/)
- [Docker Compose](https://docs.docker.com/compose/install/)
- Optionally, an existing [CockroachDB database](https://www.cockroachlabs.com/get-started-cockroachdb/)

### Step 1: Get the docker-compose file

Get the Hasura docker-compose file:

```bash
# in a new directory run
wget https://raw.githubusercontent.com/hasura/graphql-engine/master/install-manifests/docker-compose-cockroach/docker-compose.yaml
# or run
curl https://raw.githubusercontent.com/hasura/graphql-engine/master/install-manifests/docker-compose-cockroach/docker-compose.yaml -o docker-compose.yaml
```

### Step 2: Run Hasura GraphQL Engine and a CockroachDB instance

The following command will run Hasura along with a Postgres database required for its functioning.

```bash
$ docker compose up -d
```

Check that the containers are running:

```
$ docker ps

CONTAINER ID   IMAGE                 ... CREATED        STATUS          PORTS            ...
a6956d1492fd   hasura/graphql-engine ... 1 minute ago   Up 10 seconds   8080->8080/tcp   ...
f0931e41c608   cockroach             ... 1 minute ago   Up 10 seconds   26257->26257/tcp ...
42cd380d6ceb   postgres              ... 1 minute ago   Up 10 seconds   5432/tcp         ...

Please do note that you will see a Postgres database running, which is used by Hasura to store its configuration (Hasura Metadata).
```

### Step 3: Open the Hasura Console

Head to `http://localhost:8080/console` to open the Hasura Console.

### Step 4: Add your CockroachDB database as a source to Hasura

In the `Data > Data Manager > Connect Existing Database` section on the Console, select `CockroachDB` from the
`Data Source Driver` dropdown and add the connection string directly or through an environment variable. As CockroachDB
speaks the same protocol as Postgres, the connection string will start with `postgres://`, i.e, there is no difference
between CockroachDB's connection strings and Postgres’s connection strings.

<Thumbnail src="/img/databases/cockroachdb-postgres/1-add-source.png" alt="Add source" width="1100px" />

If you're testing Hasura with CockroachDB running locally,
[read this guide](/deployment/deployment-guides/docker.mdx#docker-networking) on Docker networking if you're not sure
how to reach your CockroachDB database from the Hasura docker container on Linux, Mac or Windows.

<Thumbnail
  src="/img/databases/cockroachdb-postgres/2-add-source.png"
  alt="Add source added with docker-compose"
  width="1100px"
/>

This example uses the DB url `postgresql://root@cockroach:26257/hasura`, with the service name `cockroach`, as both
Hasura and the CockroachDB services are configured in the above-mentioned `docker-compose.yaml` file.

Once you add the database, you'll see your database pop up on the sidebar.

### Optional: Populate the CockroachDB database

The following examples use `author` and `articles` tables, which can be set up as follows.

1. Connect to the CockroachDB container and start the `sql` command line tool:

```bash
docker exec -it docker-compose-cockroach-cockroach-1 ./cockroach sql --insecure
```

2. Once the command line tool has started, execute the following to set up example tables:

```sql
CREATE TABLE author(
    id serial PRIMARY KEY,
    name text UNIQUE,
    "createdAt" timestamp
);

CREATE TABLE article (
    id SERIAL PRIMARY KEY,
    title TEXT,
    content TEXT,
    author_id INTEGER REFERENCES author(id),
    is_published BOOLEAN
);

-- Inserting sequential ids for demo purposes
-- See https://www.cockroachlabs.com/docs/v22.2/serial.html
INSERT INTO
    author (id, name, "createdAt")
VALUES
    (1, 'Author 3', '2017-09-21T09:39:44'),
    (2, 'Author 4', '2017-09-21T09:50:44');

INSERT INTO
    article (title, content, author_id, is_published)
VALUES
    (
        'Article 1',
        'Sample article content 1',
        1,
        false
    ),
    (
        'Article 2',
        'Sample article content 2',
        1,
        TRUE
    ),
    (
        'Article 3',
        'Sample article content 3',
        2,
        TRUE
    );

```

### Step 5: Track existing tables or create new tables

If you have existing tables, head to the database page by clicking on the database name on the sidebar. You should see a
list of tables.

<!--

   .. thumbnail:: /img/databases/ms-sql-server/3-manage-mydb.png
      :alt: Manage my-db
      :width: 1000px

-->

Track tables selectively or all of them so that Hasura can introspect the tables and create the corresponding GraphQL
schema.

<Thumbnail src="/img/databases/cockroachdb-postgres/4-track-tables.png" alt="Track tables" width="1100px" />

If you have foreign keys, you'll also see suggested relationships. Again, you can choose to track them selectively or
all at once.

<Thumbnail
  src="/img/databases/cockroachdb-postgres/5-track-rels.png"
  alt="Track foreign-key relationships"
  width="1100px"
/>

If you don't have existing tables, go ahead and add new tables and data and try out some queries, just like with a
regular Postgres database.

<Thumbnail src="/img/databases/cockroachdb-postgres/6-add-tables.png" alt="Add a new table" width="1100px" />

### Step 6: Try out a GraphQL query

Head to the `API` tab in the Console and try running a GraphQL query! Use the explorer sidebar on GraphQL to get help in
creating a GraphQL query.

<Thumbnail src="/img/databases/cockroachdb-postgres/7-make-graphql-query.png" alt="Make GraphQL query" width="1100px" />

## Keep up to date

Hasura currently supports [queries](/queries/postgres/index.mdx),
[relationships](/schema/postgres/table-relationships/index.mdx), and [mutations](/mutations/postgres/index.mdx) on
CockroachDB.

Please refer to the [Postgres docs](/queries/postgres/index.mdx) on how you can try these features out via the Console
or by manipulating Metadata in JSON/YAML directly.

If you'd like to stay informed about the status of CockroachDB support, subscribe to our newsletter and join our
discord!

- https://hasura.io/newsletter/
- https://discord.com/invite/hasura
